Running the Application

Start the backend and frontend servers and access Iquea Commerce

This guide shows you how to run Iquea Commerce locally, access the application, and troubleshoot common startup issues.

Starting the Application

Iquea Commerce consists of two separate servers that must run simultaneously:

1. Backend API (Spring Boot on port 8080)
2. Frontend UI (Vite dev server on port 5173)

You’ll need two terminal windows open - one for the backend and one for the frontend.

---

Running the Backend

1. Navigate to Backend Directory

   Open a terminal and navigate to the backend folder:

   cd Iqüea_back
   
2. Start the Spring Boot Server

   Run the application using Maven Wrapper:

   Linux/macOS

   ./mvnw spring-boot:run
   

   First startup may take 30-60 seconds as Hibernate creates database tables and loads initial data from data.sql.

3. Verify Backend is Running

   Look for this message in the console:

   Started IqueaApplication in X.XXX seconds (process running for X.XXX)
   

   The backend API is now accessible at:

   http://localhost:8080
   

   Test the API:

   curl http://localhost:8080/api/productos
   

   You should receive a JSON response with the list of products.

---

Running the Frontend

1. Open a New Terminal

   Keep the backend terminal running and open a second terminal window.

2. Navigate to Frontend Directory

   cd Iquea_front
   
3. Start the Vite Dev Server

   npm run dev
   

   You should see output similar to:

   VITE v7.3.1  ready in XXX ms
   
   ➜  Local:   http://localhost:5173/
   ➜  Network: use --host to expose
   ➜  press h + enter to show help
   
4. Access the Application

   Open your browser and navigate to:

   http://localhost:5173
   

   The Iquea Commerce homepage should load with the product catalog.

---

Accessing the Application

Application URLs

Service	URL	Description
Frontend (UI)	http://localhost:5173	React application (Vite dev server)
Backend (API)	http://localhost:8080	Spring Boot REST API
API Endpoints	http://localhost:8080/api/*	RESTful API resources

Test User Accounts

The application comes with pre-configured test accounts loaded from data.sql:

Admin Account

Username: admin
Password: password123
Permissions: Full product and category management

Customer Account 1

Username: maria123
Password: password123
Permissions: Browse products, place orders

Customer Account 2

Username: carlos99
Password: password123
Permissions: Browse products, place orders

Login credentials are case-sensitive. Make sure to use lowercase usernames.

---

Testing the Application

1. Browse Products (No Authentication Required)

• Visit http://localhost:5173
• Browse the product catalog organized by categories
• Use the search functionality
• View product details

2. Login as Customer

1. Click the Login button
2. Enter credentials:
   • Username: maria123
   • Password: password123
3. You can now:
   • Add products to cart
   • Place orders
   • View order history

3. Login as Admin

1. Log out if currently logged in
2. Login with admin credentials:
   • Username: admin
   • Password: password123
3. You can now:
   • Create new products
   • Edit existing products
   • Delete products
   • Manage categories

4. Test API Endpoints

Get All Products (Public)

curl http://localhost:8080/api/productos

---

Stopping the Application

Stop Backend (Spring Boot)

In the backend terminal, press:

Ctrl + C

The Spring Boot application will gracefully shut down.

Stop Frontend (Vite)

In the frontend terminal, press:

Ctrl + C

The Vite dev server will stop immediately.

---

Troubleshooting Startup Issues

Backend Issues

Error: “Port 8080 already in use”

Problem: Another application is using port 8080.

Solution 1: Stop the conflicting process:

# Linux/macOS
lsof -ti:8080 | xargs kill -9

# Windows (PowerShell)
Get-Process -Id (Get-NetTCPConnection -LocalPort 8080).OwningProcess | Stop-Process

Solution 2: Change the backend port in application.properties:

server.port=9090

Don’t forget to update CORS configuration if you change the port.

---

Error: “Access denied for user ‘root’@‘localhost’”

Problem: Database credentials are incorrect or user doesn’t have permissions.

Solutions:

1. Verify MySQL is running:

   sudo systemctl status mysql  # Linux
   net start MySQL80            # Windows
   

2. Test database connection:

   mysql -u root -p
   

3. Update credentials using environment variables:

   export DB_USERNAME="your_username"
   export DB_PASSWORD="your_password"
   

4. Grant database permissions:

   GRANT ALL PRIVILEGES ON apiIquea.* TO 'root'@'localhost';
   FLUSH PRIVILEGES;
   

---

Error: “Table ‘apiIquea.producto’ doesn’t exist”

Problem: Database schema wasn’t created automatically.

Solutions:

1. Verify application.properties setting:

   spring.jpa.hibernate.ddl-auto=update
   

2. Check database URL includes createDatabaseIfNotExist:

   spring.datasource.url=jdbc:mysql://localhost:3306/apiIquea?createDatabaseIfNotExist=true
   

3. Manually create database:

   CREATE DATABASE apiIquea CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   

4. Restart the backend to trigger schema creation.

---

Error: “Failed to load initial data from data.sql”

Problem: Data initialization script failed, often due to constraint violations or existing data.

Solutions:

1. Drop and recreate database:

   DROP DATABASE apiIquea;
   CREATE DATABASE apiIquea CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   

2. Temporarily change ddl-auto to create:

   spring.jpa.hibernate.ddl-auto=create
   
   ddl-auto=create will drop all tables on startup. Change back to update after successful initialization.

---

Frontend Issues

Error: “Port 5173 already in use”

Problem: Another Vite dev server or application is using port 5173.

Solution 1: Kill the process:

# Linux/macOS
lsof -ti:5173 | xargs kill -9

# Windows
netstat -ano | findstr :5173
taskkill /PID <PID> /F

Solution 2: Specify a different port:

npm run dev -- --port 5174

---

Error: “Failed to fetch” or “Network Error”

Problem: Frontend can’t connect to backend API.

Solutions:

1. Verify backend is running:

   curl http://localhost:8080/api/productos
   

2. Check CORS configuration in SecurityConfig.java:

   configuration.setAllowedOrigins(Arrays.asList("http://localhost:5173"));
   

3. Clear browser cache and cookies (Ctrl+Shift+Delete)

4. Check browser console for specific error messages (F12)

---

Error: “Module not found” or “Cannot find module”

Problem: Node dependencies are missing or corrupted.

Solutions:

1. Reinstall dependencies:

   rm -rf node_modules package-lock.json
   npm install
   

2. Clear npm cache:

   npm cache clean --force
   npm install
   

---

Authentication Issues

Problem: “Invalid credentials” when logging in

Solutions:

1. Verify initial data was loaded:

   USE apiIquea;
   SELECT * FROM Usuario;
   

2. Check passwords are hashed with BCrypt (they should start with $2a$ or $2b$)

3. Ensure usernames are lowercase

4. Re-run data.sql manually if users are missing:

   mysql -u root -p apiIquea < src/main/resources/data.sql
   

---

Problem: JWT token expires immediately

Solution: Check JwtUtil.java expiration setting:

private static final long EXPIRATION_MS = 86400000L; // 24 hours in milliseconds

Ensure your system clock is set correctly (JWT uses timestamps).

---

Development Tips

Hot Reload

• Backend: Spring Boot DevTools enables automatic restart on code changes. Just save your Java files and the server will restart.
• Frontend: Vite provides instant Hot Module Replacement (HMR). Changes to React components appear immediately without full page reload.

Viewing Logs

Backend logs: All SQL statements and Spring Boot logs appear in the terminal where you ran mvnw spring-boot:run.

Frontend logs: Use browser DevTools (F12) to view console logs, network requests, and errors.

Database Inspection

Option 1: MySQL Workbench (GUI)

Connect to localhost:3306 and browse the apiIquea database.

Option 2: Command Line

mysql -u root -p
mysql> USE apiIquea;
mysql> SHOW TABLES;
mysql> SELECT * FROM Producto LIMIT 5;

---

Next Steps

Now that your application is running:

• Explore the API Reference to learn about available endpoints
• Read the Architecture Overview to understand the system design
• Check out the Development Guide for contribution guidelines

For production deployment, refer to the Deployment Guide (coming soon) for instructions on building production bundles and deploying to cloud platforms.